Chrome 插件 MV3 配置清单

前言

有过开发 Chrome 插件经历的朋友应该知道，开发插件时需要在根目录添加一个 manifest.json 配置清单，清单内容需要根据需要添加，每次开发时基本需要去翻配置文档，但 Chrome 开发文档繁杂难找，同时还需要科学上网，每次查起来都要花费不少时间，所以整理一份清单表格作为参考使用。

完整清单

字段	类型	描述
manifest_version	整数	用于指定扩展程序使用的清单文件格式版本。唯一支持的值是 3。
name	字符串	用于在 Chrome 应用商店、安装对话框和用户的 Chrome 扩展程序页面 (chrome://extensions) 中标识扩展程序。长度上限为 75 个字符。如需了解如何使用特定于语言区域的名称，请参阅国际化。
version	字符串	用于标识扩展程序版本号的字符串。如需了解如何设置版本号的格式，请参阅版本。
description	字符串	用于描述 Chrome 应用商店和用户扩展程序管理页面上的扩展程序。长度上限为 132 个字符。如需了解如何将说明本地化，请参阅国际化。
icons	对象	代表扩展程序的一个或多个图标。如需了解最佳做法，请参阅图标。
action	对象	定义扩展程序图标在 Google 工具栏中的外观和行为。如需了解详情，请参阅 chrome.action。
author	字符串	指定用于创建扩展程序的帐号的电子邮件地址。
background	对象	指定包含扩展程序 Service Worker 的 JavaScript 文件，该 Service Worker 充当事件处理脚本。如需了解详情，请参阅扩展程序 Service Worker 简介。
chrome_settings_overrides	对象	定义所选 Chrome 设置的替换项。如需了解详情，请参阅替换 Chrome 设置。
chrome_url_overrides	对象	定义默认 Chrome 网页的替换值。如需了解详情，请参阅替换 Chrome 网页。
commands	对象	定义扩展程序中的键盘快捷键。如需了解详情，请参阅 chrome.commands。
content_scripts	对象	指定在用户打开某些网页时要使用的 JavaScript 或 CSS 文件。如需了解详情，请参阅内容脚本。
content_security_policy	对象	定义对扩展程序可使用的脚本、样式和其他资源的限制。如需了解详情，请参阅内容安全政策。
cross_origin_embedder_policy	字符串	为 Cross-Origin-Embedder-Policy HTTP 标头指定值，该值用于配置在扩展程序页面中嵌入跨源资源。
cross_origin_opener_policy	字符串	指定 Cross-Origin-Opener-Policy HTTP 标头的值，可让您确保顶级扩展程序页面不会与跨源文档共享浏览上下文组。
declarative_net_request	对象	定义 declarativeNetRequest API 的静态规则，以允许屏蔽和修改网络请求。
default_locale	字符串	用于定义支持多个语言区域的扩展程序的默认语言。例如“en”和“pt_BR”。此键在已本地化的扩展程序中是必需的，不得在未本地化的扩展程序中使用。如需了解详情，请参阅国际化。
devtools_page	字符串	定义使用 DevTools API 的页面。
export	对象	允许从扩展程序导出资源。如需了解详情，请参阅导出。
externally_connectable	对象	指定哪些其他网页和扩展程序可以连接到您的扩展程序。如需了解详情，请参阅 "externally_connectable"。
homepage_url	字符串	用于指定扩展程序首页的网址。如未定义，则主页默认为扩展程序的 Chrome 应用商店页面。如果您在自己的网站上托管扩展程序，此字段会特别有用。
host_permissions	字符串数组	列出允许您的扩展程序与之互动的网页，使用网址匹配模式定义。系统会在安装应用时请求这些网站的用户权限。如需了解详情，请参阅主机权限。
import	数组	允许将资源导入扩展程序。如需了解详情，请参阅导入。
incognito	字符串	定义扩展程序在无痕模式下的行为方式。支持的值包括 "spanning"、"split" 和 "not_allowed"。如需了解详情，请参阅无痕模式。
key	字符串	指定用于各种开发用例的扩展程序 ID。如需了解详情，请参阅键。
minimum_chrome_version	字符串	定义可安装扩展程序的最低 Chrome 版本。该值必须是现有 Chrome 浏览器版本字符串的子字符串，例如 "107" 或 "107.0.5304.87"。如果用户的 Chrome 版本低于最低版本，则会在 Chrome 应用商店中看到“不兼容”警告，并且无法安装您的扩展程序。如果您将此扩展程序添加到现有扩展程序，则 Chrome 版本较低的用户不会收到您的扩展程序的自动更新。这包括处于临时模式的企业用户。
oauth2	对象	允许使用 OAuth 2.0 安全 ID。此键的值必须是具有 "client_id" 和 "scopes" 属性的对象。如需了解详情，请参阅 OAuth 2.0 教程。
omnibox	对象	允许此扩展程序在 Chrome 地址栏中注册关键字。如需了解详情，请参阅多功能框。
optional_host_permissions	字符串数组	为您的扩展程序声明可选的主机权限。。
optional_permissions	字符串数组	为您的扩展程序声明可选权限。
options_page	字符串	指定 options.html 文件的路径，以使扩展程序用作选项页面。如需了解详情，请参阅为用户提供选项。
options_ui	对象	指定 HTML 文件的路径，该文件允许用户从 Chrome 扩展程序页面更改扩展程序选项。如需了解详情，请参阅嵌入式选项。
permissions	字符串数组	允许使用特定的扩展程序 API。如需了解一般说明，请参阅权限。各个 API 的参考页面列出了它们所需的权限。
requirements	对象	列出使用扩展程序所需的技术。如需查看受支持要求的列表，请参阅要求。
sandbox	对象	定义一组无权访问扩展程序 API 或直接访问非沙盒化页面的扩展程序页面。如需了解详情，请参阅沙盒。
short_name	字符串	其中包含在字符空间有限时要使用的扩展名称的缩写版本。长度上限为 12 个字符。如果未指定，则会显示“name”键的截断版本。
side_panel	对象	标识要在 sidePanel 中显示的 HTML 文件。
storage	对象	为代管式存储区域声明 JSON 架构。如需了解详情，请参阅存储区域的清单。
tts_engine	对象	将扩展程序注册为文字转语音引擎。如需了解详情，请参阅 ttsEngine API。
update_url	字符串	一个字符串，包含扩展程序的更新页面的网址。如果您在 Chrome 应用商店之外托管扩展程序，请使用此密钥。
version_name	字符串	一个描述扩展程序版本的字符串。例如 "1.0 beta" 和 "build rc2"。如果未指定，则“版本”值会显示在扩展程序管理页面上。
web_accessible_resources	对象	定义扩展程序中可由网页或其他扩展程序访问的文件。如需了解详情，请参阅可通过 Web 访问的资源。
file_browser_handlers	对象	提供对 fileBrowserHandler API 的访问权限，该 API 可让扩展程序访问 ChromeOS 文件浏览器。
file_handlers	对象	指定让 ChromeOS 扩展程序处理的文件类型。如需了解详情，请参阅 file_handlers。
file_system_provider_capabilities	对象	允许访问 fileSystemProvider API，以便扩展程序创建 ChromeOS 可以使用的文件系统。
input_components	对象	允许使用 Input Method Editor API。如需了解详情，请参阅 input_components。

子清单

background

字段名	类型	是否必填	描述
service_worker	字符串	✅	指定单个要注册 Service Worker 的 JavaScript 文件
type	字符串	❌	如需在 service worker 中使用 import 语句，添加 "type" 字段并指定为 "module"

chrome_settings_overrides

字段名	类型	是否必填	描述
alternate_urls	字符串数组	❌	除 search_url 之外，还可使用的网址格式列表。
encoding	字符串	❌	用于搜索字词的编码。如果您没有设置 prepopulated_id，则必须执行此操作。
favicon_url	字符串	❌	搜索引擎的图标网址。如果您没有设置 prepopulated_id，则必须执行此操作。
homepage	字符串	❌	首页的新值。
image_url	字符串	❌	搜索引擎用于图片搜索的网址。如果您不这样做，则表示引擎不支持图片搜索。
image_url_post_params	字符串	❌	image_url 的 post 参数。
is_default	布尔值	✅	指定是否应将搜索服务提供商设置为默认搜索引擎。
keyword	字符串	❌	搜索引擎的多功能框关键字。如果您没有设置 prepopulated_id，则必须执行此操作。
name	字符串	❌	向用户显示的搜索引擎的名称。如果您没有设置 prepopulated_id，则必须执行此操作。
prepopulated_id	整数	❌	Chrome 内置搜索引擎的 ID。
search_provider	对象	❌	搜索引擎。
search_url	字符串	✅	搜索引擎使用的搜索网址。
search_url_post_params	字符串	❌	search_url 的 post 参数。
startup_pages	字符串数组	❌	一个长度为 1 的数组，其中包含将用作启动页的网址。
suggest_url	字符串	❌	搜索引擎用于获取建议的网址。如果未使用此属性，则引擎不支持建议。
suggest_url_post_params	字符串	❌	suggest_url 的 post 参数。

content script

名称	类型	是否必填	描述
matches	字符串数组	✅	指定要将此内容脚本注入哪些网页。如需详细了解这些字符串的语法，请参阅匹配模式；如需详细了解如何排除网址，请参阅匹配模式和 glob。
css	字符串数组	❌	要注入到匹配页面的 CSS 文件列表。这些元素会按照它们在此数组中出现的顺序进行注入，然后再为网页构建或显示任何 DOM。
js	字符串数组	❌	要注入到匹配页面的 JavaScript 文件的列表。系统会按照文件在此数组中出现的顺序注入文件。此列表中的每个字符串都必须包含扩展程序根目录中某项资源的相对路径。前导斜杠（“/”）会自动剪除。
run_at	RunAt	❌	指定何时应将脚本注入到网页中。默认值为 document_idle。
match_about_blank	boolean	❌	脚本是否应注入到 about:blank 帧中，其中父帧或起始帧与 matches 中声明的模式之一匹配。默认值为 false。
match_origin_as_fallback	boolean	❌	脚本是否应注入由匹配的来源创建的帧，但其网址或来源可能与模式不直接匹配。其中包括具有不同架构的帧，例如 about:、data:、blob: 和 filesystem:。另请参阅在相关帧中注入。
world	ExecutionWorld	❌	用于执行脚本的 JavaScript 环境。默认值为 ISOLATED。另请参阅在隔离的世界中工作。

content_security_policy

字段名	字段类型	描述
extension_pages	字符串	包含网络平台内容安全政策，用于指定对扩展程序可以使用的脚本、样式和其他资源的限制
sandbox	字符串	对于沙盒网页的默认政策要比扩展程序页面宽松得多，因为沙盒页面无权访问扩展程序 API，也不能直接访问非沙盒化页面。可根据需要自定义沙盒内容安全政策。

externally_connectable

字段名	字段类型	描述
ids	字符串数组	允许连接的扩展程序的 ID。如果留空或未指定，则任何扩展程序或应用都无法连接。通配符 "*" 将允许连接所有扩展程序和应用。
matches	字符串数组	允许连接的网页的网址格式。如果留空或未指定，则任何网页都无法连接。格式不能包含通配符网域，也不能包含（有效）顶级域名的子网域。
accepts_tls_channel_id	布尔值	让扩展程序能够使用连接到该扩展程序的网页的 TLS 通道 ID。网页还必须选择向扩展程序发送 TLS 通道 ID，方法是在 Runtime.connect 的 connectInfo 或 Runtime.sendMessage 的选项中将 includeTlsChannelId 设置为 true。如果设置为 false，则在任何情况下都永远不会设置 runtime.MessageSender.tlsChannelId。

options_ui

字段名	类型	是否必填	描述
page	字符串	✅	指定选项页面相对于扩展程序根目录的路径。
open_in_tab	布尔值	❌	用于指示是否在新标签页中打开扩展程序的选项页面。如果设为 false，该扩展程序的选项页面会嵌入 chrome://extensions 中，而不会在新标签页中打开。

side_panel

字段名	类型	是否必填	描述
default_path	字符串	✅	sidepanel html 文件路径

web_accessible_resources

字段名	字段类型	描述
resources	字符串数组	一个字符串数组，每个字符串都包含从扩展程序根目录到给定资源的相对路径。资源中可能会使用星号 () 表示通配符匹配。例如，"/images/" 会递归公开扩展程序的 images/ 目录中的所有内容，而 "*.png" 会公开所有 PNG 文件。
matches	字符串数组	一个字符串数组，每个字符串都包含一个匹配模式，用于指定哪些网站可以访问这组资源。只有来源用于匹配网址。来源包括子网域匹配。如果格式中的路径不是“/*”，Google Chrome 就会发出“匹配模式无效”错误。
extension_ids	字符串数组	一个字符串数组，每个字符串都包含可以访问资源的扩展程序的 ID。

file_handlers

字段名	字段类型	是否必填	描述
file_handlers	字典	❌	指定扩展程序可以打开的文件类型。
action	字符串	✅	指定打开文件时显示的 HTML 文件。文件必须位于您的扩展名中。处理文件（无论是显示还是以其他方式使用）是通过 JavaScript 使用合适的网络平台 API 完成的。此代码必须位于通过 <script> 标记包含的单独 JavaScript 文件中。
name	字符串	✅	必需。简单易懂的操作说明。
accept	字典	✅	"action" 中指定的页面可以处理的文件类型。字典中的项是一个键值对，其中键是 MIME 类型，值是文件扩展名数组。键仅允许使用已知的 MIME 类型。允许使用自定义文件类型，但自定义类型的键必须是已知的 MIME 类型，并且 MIME 类型和自定义文件类型之间的映射必须受底层操作系统支持。
launch_type	对象	❌	指定应在单个客户端还是多个客户端中打开多个文件。有效值为 "single-client" 和 "multiple-clients"。默认值为 "single-client"。

file_system_provider

字段名	字段类型	是否必填	描述
configurable	布尔值	❌	是否支持通过 onConfigureRequested 进行配置。默认值为 false。
multiple_mounts	布尔值	❌	是否支持多个（多个）装载的文件系统。默认值为 false。
watchable	布尔值	❌	是否支持设置观察器并通知更改。默认值为 false。
source	枚举（“file”“device”“network”）	✅	已装载文件系统的数据源。

input_components

字段名	类型	是否必填	描述
name	字符串	✅	输入组件对象的名称。
id	字符串	❌	组件对象 ID。
language	字符串（或字符串数组）	❌	指定语言或适用语言列表。示例："en", ["en", "pt"]
layouts	字符串（或字符串数组）	❌	输入法的列表。请注意，ChromeOS 每种输入法仅支持一种布局。如果指定了多个布局，则未定义选择顺序。因此，强烈建议扩展程序仅为每种输入法指定一个布局。对于键盘布局，xkb: 前缀表示这是键盘布局扩展。
示例：["us::eng"]
input_view	字符串	❌	用于指定扩展程序资源。
options_page	字符串	❌	用于指定扩展程序资源。如果未提供，系统将使用默认扩展程序的选项页面。

结语

由于子清单的配置过于杂乱，整理起来很麻烦， 所以只整理了一部分子清单，其他子清单的配置还是需要上官网查阅。

相关链接

• Chrome 清单配置： https://developer.chrome.com/docs/extensions/reference/manifest
• Chrome 插件教程：https://developer.chrome.com/docs/extensions/get-started/tutorial/hello-world